








          LBL - Symbolic Labels in Text Documents





1.  Introduction

     _l_b_l is a pre-processor for _t_r_o_f_f and _n_r_o_f_f which allows
Sections,  Figures,  Tables,  etc.,  to  be  referred  to by
symbolic names rather than  by  absolute  number.   It  will
handle forward references as well as backward ones.

     Uses of  a  label  in  the  text  are  indicated  by  a
delimiter  character (default '@', but resettable), followed
by a _t_y_p_e name (e.g. "TABLE", "EQN", etc.), followed by  the
label itself (e.g. "Profits-1983").  Each such occurrence is
replaced  by  a  reference  number;  the  default  style  of
numbering  is  a sequence of period-separated arabic numbers
(e.g. 2.4.1)  but  this  is  resettable.   Finally,  another
delimiter is required to close the reference (cf. the use of
delimiters in _e_q_n for in-line equations).

Examples:

        For full details refer to Table @TABLE Profits-1983@.
        As we saw in Chapter @chap intro@, ...
        Figure @fig wing-profile@ shows the airflow patterns ...


     Labels may be defined at any point in  the  text.   The
definition looks like a _t_r_o_f_f macro, and the definition line
is retained in the original text.   By  default,  the  macro
used  is  ".L=",  but  this can be reset.  The macro takes 3
arguments: a type-name, a level-number, and a label-name.

     The type-name corresponds to  that  used  to  signal  a
label  occurrence  in  the text.  There is no restriction on
the choice of name; any sequence of non-blank characters may
be used.  Upper- and lower-case letters _a_r_e distinguished.

     The  level-number  corresponds  to   the   header-level
numbers  used  by  the .NH macro in _m_s, the .sh macro in _m_e,
etc.  The index at the given level is incremented by 1,  and
all higher indexes set to 0.  Initially, all indexes are set
to 0 by default, but other starting values  may  be  chosen.
There is an implementation-defined restriction on the number
of levels of index (currently 20);  it  is  not  anticipated
that this will lead to problems.

     The label may be any sequence of non-blank  characters;









                           - 2 -


the   same  label  may  be  used  in  more  than  one  type.
Furthermore, the special label-name ``*''  can  be  used  to
increment  the  appropriate level-counter without defining a
label at all; this is useful, for example, when all  tables,
figures,  etc.,  in  a section take their initial index from
the section number: two ways of doing this would be:

a.
    .L= section 1 this-section
    .L= last table 0
    .L= last figure 0
    ...
    ... refer to table @section this-section@.@table profits@ ...
    ... see figure @section this-section@.@figure structure@ ...
    ...
    .L= table 1 profits
    ...
    .L= figure 1 structure
    ...

(see section 3 for the use of
``.L= last ...'')

b.
    .L= section 1 this-section
    .L= table 1 *
    .L= figure 1 *
    ...
    ... refer to table @table profits@ ...
    ... see figure @figure structure@ ...
    ...
    .L= table 2 profits
    ...
    .L= figure 2 structure
    ...

It is largely a matter of taste which technique is used; the
former  is more long-winded, but avoids the need to remember
to keep the tables  and  figures  in  step  every  time  the
section is updated.  Yet a third possibility (similar to the
first) would be:

c.
    .L= section 1 this-section
    .ds Sc "@section this-section@
    .L= last table 0
    ...
    ... refer to table .@table profits@
    etc.

making use of the string-definition facility within _n_r_o_f_f.

     It is important to be  aware  that  all  processing  on
labels  is done before _t_r_o_f_f processes the text; attempts to









                           - 3 -


build label-references by  using  macros  or  _t_r_o_f_f  strings
registers will almost certainly not work as expected.

2.  Command Line Options

     Options to _l_b_l are set in the command line,  which  has
the form

        lbl [ -d_d_e_l_i_m ] [ -m_m_a_c_r_o ] [ -l ] [ -s ]


-d   _d_e_l_i_m  is  the  character  used  to   delimit   in-line
     occurrences of label references (default ``@'');

-m   _m_a_c_r_o is the 2-character name of a  _t_r_o_f_f  macro  which
     introduces label definitions, etc. (default ``L='');

-l   causes a listing of label-definitions to be written  to
     the  standard error stream.  Each label-type is listed,
     together with its print format, followed by a line  for
     each  label  of that type, showing label-name, file and
     line where it is defined, and value;

-s   causes the generation of the _t_r_o_f_f  input  file  to  be
     suppressed; setting -_s automatically also sets -_l.

3.  Control directives

     In addition to defining labels, the .L= macro  (or  its
substitute)  can  be used for several other purposes.  These
are all indicated by commands of the form

        .L= _c_o_m_m_a_n_d _a_r_g_u_m_e_n_t ...

where the _c_o_m_m_a_n_ds are reserved words which may not be  used
as  type-names.   These  commands  allow  control  over  the
initialisation of label values, the print format of  labels,
and thelabel reference delimiter.

.L= delimiter off
     turns off interpretation  of  the  delimiter  character
     altogether;  subsequent  text is copied literally until
     another _d_e_l_i_m_i_t_e_r command is encountered;

.L= delimiter _c_h_a_r_a_c_t_e_r
     resets the delimiter in subsequent text  to  the  given
     character;

.L= format _t_y_p_e_n_a_m_e _s_t_r_i_n_g
     sets the print format for labels of the  given  type  -
     see section 3.1;

.L= last _t_y_p_e_n_a_m_e _c_o_u_n_t_1 _c_o_u_n_t_2 ...
     resets the counters for _t_y_p_e_n_a_m_e  as  though  the  last









                           - 4 -


     label  generated  had  been  _c_o_u_n_t_1._c_o_u_n_t_2... (with all
     omitted counts taken as 0).

3.1.  Print formats

     The default print format for a label is as  a  sequence
of  period-separated  arabic  numerals.  However, it is also
possible  to  specify  alphabetic  or  roman  labels,  or  a
mixture,  and  to have separators other than a period.  This
is governed by the format given in a ``.LE format'' command.

     Such a format contains escape sequences (flagged  by  a
``%'' character) and literal text.  The text is copied until
an escape  sequence  is  encountered;  such  a  sequence  is
replaced by the index for the next level of the label value,
printed in one of the following formats:

%1   Arabic  numerals   (without   non-significant   leading
     zeros);

%0   As %1, but offset by 1 so that the first value  printed
     will be 0 rather than 1;

%a   Lower-case alphabetics, starting  at  ``a'';  ``z''  is
     followed by ``aa'', etc.;

%A   Upper-case alphabetics;

%i   Lower-case roman numerals (with some  odd  choices  for
     large  numbers,  consistent  with  the  roman  numerals
     printed by _t_r_o_f_f).

%I   Upper-case roman numerals.

A ``%'' followed  by  any  other  character  (in  particular
another ``%'') prints as that character.

4.  Limits

     _L_b_l imposes  no  limit  on  the  size  of  text  to  be
processed,  but  (like  _r_e_f_e_r)  needs  to act on a text as a
whole, rather than processing individual files.   The  limit
on  the  number  of  levels of header is unlikely to prove a
problem.  The number of labels which may be used is  limited
only by the amount of memory available to a process; even on
a small machine it is possible to handle a few hundred label
definitions.

5.  Further Examples

     The copying of the definition macros makes it  possible
to use them as _t_r_o_f_f macros, as in the following example:











                           - 5 -



        .de L=
        .ie '\\$1'sec' .NH \\$2
        .el .ie '\\$1'table' .if !'\\$3'*' \{
        .DS C
        Table '\\$3' about here
        .DE
        \}
        .el .if '\\$1'fig' .if !'\\$3'*' \{
        .DS C
        Figure '\\$3' about here
        .DE
        \}
        ..
        .nr LL 5i
        .ND
        .TL
        Example of LBL
        .L= sec 1 intro
        Introduction
        .L= table 1 *
        .PP
        We begin with a small table (Table @table opening@).
        .L= table 2 opening
        and consider things in more detail in Section
        @sec cont@.
        .L= sec 1 cont
        Continuation
        .L= table 1 *
        .PP
        In this continuation we refer back to Section
        @sec intro@, which contained
        Table @table opening@, and present more detailed
        information in Table
        @table detail@.
        .L= table 2 detail
        .L= sec 2 subcont
        Sub-continuation
        .PP
        In which we further refine things, as shown in
        Table @table mega-detail@ below.
        .L= table 2 mega-detail

In the above, the ``.L= sec'' macros automatically  generate
the numbered headings by expanding to the _m_s ``.NH'' macros,
while the  ``table''  definitions  cause  the  insertion  of
figures such as

                 Table 'detail' about here

The above example thus produces the following:












                           - 6 -



                          Example of LBL





        _1.  _I_n_t_r_o_d_u_c_t_i_o_n

             We begin with a small table (Table 1.1).


                    Table 'opening' about here

         and consider things in more detail in Section 2.

        _2.  _C_o_n_t_i_n_u_a_t_i_o_n

             In this continuation we refer back to Section
        1,  which  contained  Table  1.1, and present more
        detailed information in Table 2.1.


                    Table 'detail' about here



        _2._1.  _S_u_b-_c_o_n_t_i_n_u_a_t_i_o_n

             In which we further refine things,  as  shown
        in Table 2.2 below.


                  Table 'mega-detail' about here


     The alphabetic formats may be useful for such things as
appendices, e.g.

        .L= format appendix %A
        .L= appendix 1 trade-marks
        .SH
        Appendix @appendix trade-marks@:
        List of Registered Trade Marks
        .LP
        (For the addresses of the proprietors see
        @appendix props@).
          ...
        .L= appendix 1 props

which will generate












                           - 7 -



        _A_p_p_e_n_d_i_x _A: _L_i_s_t _o_f _R_e_g_i_s_t_e_r_e_d _T_r_a_d_e _M_a_r_k_s

        (For the addresses of the proprietors see appendix B).
























































echo shar: "274 control characters may be missing from 'lbl.doc'"
